State which checkout an agent works in and what the hub is by ptr727 · Pull Request #593 · ptr727/ProjectTemplate

ptr727 · 2026-08-06T22:59:36Z

Carries the TODO.md cluster "Reaching the Hub in Your Own Checkout" whole, all four entries. They ship together because a rule telling a repository to fetch the hub while staying silent on whose clone it fetches into licenses the failure it exists to prevent.

What changed

GOVERNANCE.md "Repository Boundaries and Write Safety" gains the isolation rule as two bullets, and its opening widens to say the section bounds a write to a checkout on disk as well as a write that reaches GitHub. The unit is the task rather than the agent, on the evidence in #557 that one agent hit the hazard alone when a git mv intended for the hub landed in another repository, so a per-agent rule would have permitted exactly the thing that went wrong. The three commands that cross the boundary are named because each is correct in isolation, and the rule pairs with the mechanical habit of giving a mutating command an absolute path rather than the working directory it inherited. The second bullet covers a tree another task is already live in: the two signals that say so, the instruction to stop rather than re-apply a reverted edit, and how a footprint already left there is undone.

GOVERNANCE.md "Verification Discipline" gains the same rule for reading. A clone is whatever it last fetched rather than the branch it names, so a finding taken from one carries a date nobody stated. That section is the home because its framing that every failure under it is green describes the stale-clone failure exactly.

AGENTS.md "Fleet Bootstrap" names github.com/ptr727/ProjectTemplate as the hub, so the word that carries the whole instruction is defined where the routing lives, and the closing paragraph goes from two bounding rules to three by adding the reach rule: a checkout of your own, fetched immediately before reading, worked in rather than in one that another task is using.

README.md defines six terms inside "What This Repo Is", for a repository that carries no instruction set and therefore cannot read the bootstrap section at all. Each term names the file that answers it, which doubles as the per-task entry point #579 asks for, so audit yourself against the hub resolves to AUDIT.md and close the review loop resolves to the PR Review Etiquette contract. No new heading, so the section order spec/readme-structure.md fixes is unchanged.

.github/copilot-instructions.md points a reviewer at the four hub scripts and at the GOVERNANCE.md exception permitting such a pointer inside carried text, since without it an agent has no in-file rule telling it a scripts/prose_lint.py reference is a hub pointer rather than a broken local path. The same edit corrects the byte-locked section count from two to three, matching what spec/files.json and spec/section-model.md both declare.

host-setup/agent-safety/ carries the same two rules in the host-wide blocks, which each state that they are kept in sync with their GOVERNANCE.md counterpart deliberately, because they cover sessions no AGENTS.md reaches. The safety block's heading becomes Repository Boundaries and Write Safety to match the scope it now has and the section it mirrors, and the kit README is corrected where describing that block: it no longer states a rule count, and it names both classes the hook mechanically enforces against the three that are prose only.

Fleet impact

Four verbatim sections change, so every fleet repository shows drift until the re-vendor. That rides the visit already queued under "Fleet Sweeps" rather than owing a sweep of its own. The two host-setup blocks reach a machine only when install.py is re-run there, and the installer replaces any v\d+ marker block in place, so the version marker stays at v1 and the renamed heading is picked up with it.

Verification

Run on c039ecd against origin/develop:

python3 scripts/prose_lint.py . --diff origin/develop --summary reports 0 violations. The diff scope was confirmed non-empty first, 28 changed lines across 7 files, since a zero from an empty scope is the false clean that gate exists to prevent.
python3 scripts/repo_gate.py reports 0 issues on both eol and sha-pin.
python3 spec/validate.py reports 22 cataloged, 0 backlog repos classifying cleanly.
python3 -m unittest discover -s scripts runs 268 tests, OK.
markdownlint-cli2 over 44 files, cspell over README.md and HISTORY.md, editorconfig-checker, and actionlint all report clean.
All seven files are still CRLF, checked by byte scan rather than by file.

Review

Five findings across four rounds, every one accepted and fixed, none declined. Three arrived as suppressed comments with no thread, and are answered in pull request comments quoting each one. Two of the five were defects this pull request's own earlier rounds introduced, which is recorded in the replies rather than quietly corrected.

Not carried here

TODO.md is untouched. Its clustered form exists only on the #592 branch, so editing it here would conflict. The cluster heading is deleted after #592 merges.

#557 and #579 close on the develop to main promotion, not on this pull request.

🤖 Generated with Claude Code

A rule telling a repository to fetch the hub while staying silent on whose clone it fetches into licenses the failure it exists to prevent, so the two are one change. Repository Boundaries and Write Safety gains the isolation rule. Its unit is the task rather than the agent, since one agent moving between two repositories meets the same hazard as two agents sharing one tree. The commands that cross the boundary are ordinary ones that are correct in isolation, so the rule names them and pairs with the habit of giving a mutating command an absolute path rather than an inherited directory. A second bullet covers the tree someone else is already live in, the two signals that say so, and how a footprint already left there is undone. Verification Discipline gains the same rule for reading, since a clone is whatever it last fetched rather than the branch it names, and a stale one answers confidently instead of failing. Fleet Bootstrap names the hub as a defined term, adds the reach rule, and states whose checkout the work happens in. README.md defines the six terms a request is phrased in, for a reader whose repository carries no instruction set at all. The copilot instructions point a reviewer at the hub scripts and at the exception permitting such a pointer inside carried text, and correct the byte-locked section count from two to three to match spec/files.json. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Defines key fleet terms (for “hub”, “review loop”, “stand up”, etc.) and strengthens governance guidance around working in isolated checkouts and avoiding stale-clone reads, so agents have unambiguous, self-contained instructions and failure modes are explicitly guarded against.

Changes:

Adds explicit term definitions to README.md so requests like “audit against the hub” and “close the review loop” resolve to concrete entry-point docs.
Extends GOVERNANCE.md write-safety scope to include local working-tree hazards and adds a corresponding stale-clone warning under verification discipline.
Propagates the “hub” definition / reach guidance into AGENTS.md, .github/copilot-instructions.md, and host-wide host-setup/agent-safety/ blocks for consistency.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Defines commonly used fleet terms and adds missing reference links for those entry points.
GOVERNANCE.md	Expands write-safety to include local checkout hazards and adds stale-clone guidance under verification.
AGENTS.md	Names the hub explicitly and adds the “reach the hub in your own fetched checkout” bounding rule.
.github/copilot-instructions.md	Adds guidance that hub-script references are intentional pointers (not broken local paths) and updates byte-locked section count/constraints.
host-setup/agent-safety/claude-md-safety.md	Mirrors the new local-checkout write-safety rule in the host-wide safety block.
host-setup/agent-safety/claude-md-fleet.md	Defines the hub explicitly and adds the “reach hub via your own fetched checkout” rule to the host-wide fleet bootstrap block.

The lead read "An agent works in its own checkout" while the sentence after it states the unit is the task rather than the agent, which is the per-agent reading the rule exists to reject. The host-wide block carried the same mismatch and is corrected with it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (1)

host-setup/agent-safety/claude-md-safety.md:2

The section title says "GitHub Write Safety", but the opening paragraph now explicitly covers local working-tree writes (e.g., blanket add / hard reset) in addition to GitHub/API writes. Renaming the header would keep the scope consistent for readers skimming headings.

## GitHub Write Safety (Any Project, Every Session)

A `gh` / GitHub API write runs under the logged-in identity, so a mis-targeted write acts publicly as that account on someone else's repository, an outward-facing and hard-to-reverse act. These rules bound every write (a git push, an API mutation, a comment, a label, a merge) in every session on this machine, including ad-hoc work outside any project, and they bound a write to a checkout on disk as well, since a blanket add or a hard reset in a working tree another task is using destroys work without ever reaching GitHub. Reads are unrestricted. A committed repo's `GOVERNANCE.md` "Repository Boundaries and Write Safety" states the same rules for its fleet, and the two are kept in sync deliberately, because this file also covers sessions that `AGENTS.md` never reaches. The `gh-write-guard` PreToolUse hook enforces the mechanical half.

The heading read "GitHub Write Safety" while the section bounds a write to a checkout on disk as well, so it takes the name of the GOVERNANCE.md section it mirrors. Two claims about it in the kit README go with it: the block no longer carries three write rules, and the hook backs the GitHub writes rather than the checkout the command belongs in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ptr727 · 2026-08-06T23:09:15Z

Answering the suppressed finding from the round on 02f64e1, which has no thread to reply to.

The section title says "GitHub Write Safety", but the opening paragraph now explicitly covers local working-tree writes (e.g., blanket add / hard reset) in addition to GitHub/API writes. Renaming the header would keep the scope consistent for readers skimming headings.

Accepted and fixed in 1cc8b13. The heading is now Repository Boundaries and Write Safety (Any Project, Every Session), taking the name of the GOVERNANCE.md section it mirrors, which the block's own opening paragraph already says it is kept in sync with. The rename needs no marker-version bump, since install.py replaces the whole block by its v\d+ markers and the heading sits inside them.

Verifying it surfaced two further stale claims in host-setup/agent-safety/README.md that this pull request had introduced and nothing flagged, both fixed in the same commit:

It described the block as carrying "the same three write rules", which this pull request made four. The count is dropped rather than corrected, since a hand-maintained count in prose is the maintenance trap GOVERNANCE.md "Quantitative Claims" exists for.
It read "The write rules have a hook behind them", which now overreaches. The gh-write-guard hook watches Bash for GitHub writes and cannot see which checkout a command belongs in, so that sentence is narrowed to the GitHub write rules and says why the rest is prose only.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (1)

host-setup/agent-safety/README.md:14

The paragraph says only "The GitHub write rules have a hook behind them", but the hook also enforces the git branch-bypass protections described above (direct push/force-push/delete and --admin/--no-verify). As written, this understates what is mechanically enforced vs prose-only.

The hook is the mechanical backstop. The CLAUDE.md rules and the carried GOVERNANCE.md rules are the behavioral layer. Prose alone is not enough, since the incident happened under prose rules, so both ship. The GitHub write rules have a hook behind them, and everything else is prose only, since no hook can see which checkout a command belongs in, or what a line of text means.

Narrowing the claim to the GitHub write rules left the git operations that bypass a repository protection reading as prose only, which understates what is mechanically enforced. Both hook-backed classes are named, and the three that genuinely have no hook are named with them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ptr727 · 2026-08-06T23:13:16Z

Answering the suppressed finding from the round on 1cc8b13, which has no thread to reply to.

The paragraph says only "The GitHub write rules have a hook behind them", but the hook also enforces the git branch-bypass protections described above (direct push/force-push/delete and --admin/--no-verify). As written, this understates what is mechanically enforced vs prose-only.

Accepted and fixed in daf3f50. The narrowing in 1cc8b13 overcorrected: it was answering the checkout-isolation rule having no hook, and in doing so it swept the branch-bypass class into "everything else is prose only", which the same file's own hook description five lines above contradicts.

The sentence now names both hook-backed classes, the GitHub write rules and the git operations that bypass a repository protection, and names the three that genuinely have no hook rather than leaving them as a remainder: which checkout a command belongs in, the data a line of text quotes, and how an authorization is recorded.

Worth recording that the previous round's fix introduced this one. A narrowing word is load-bearing, and narrowing to answer one case is how a neighboring case gets swept up in the remainder.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

Suppressed comments (2)

AGENTS.md:20

The phrase "one another task is using" is missing the relative pronoun and reads ungrammatically. Consider inserting "that" so the rule is clear and scans correctly.

Three rules bound every path above. **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. **Reach the hub as a checkout of your own and fetch it immediately before reading it**, because a clone is whatever it last fetched rather than the branch it names, and work only in that checkout rather than in one another task is using, per [`GOVERNANCE.md`](./GOVERNANCE.md) "Repository Boundaries and Write Safety" and "Hub-Hosted Tooling". And **the audit is read-only**: it produces a report and never edits the repository it measures, so a fix is a separate, reviewable change.

host-setup/agent-safety/claude-md-fleet.md:11

This bullet uses "one another task is using" (missing "that"), which is grammatically incorrect and slightly obscures the intended guidance.

- **Reach the hub as a checkout of your own, fetched immediately before it is read.** A clone is whatever it last fetched rather than the branch it names, so a stale one answers confidently instead of failing, and a single file lifted out of the tree runs against whatever the caller happens to have. Work only in that checkout rather than in one another task is using, since a blanket add, a hard reset, or a branch switch in a tree someone else is editing destroys work while every command is individually correct.

"In one another task is using" opens on the fixed reciprocal pronoun, so a reader parses "one another" as a unit and backtracks on reaching the verb. Both copies of the reach rule take the explicit "that". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

ptr727 · 2026-08-06T23:16:53Z

Answering both suppressed findings from the round on daf3f50, which have no threads to reply to. They are one finding against two files, AGENTS.md and host-setup/agent-safety/claude-md-fleet.md, and both read:

The phrase "one another task is using" is missing the relative pronoun and reads ungrammatically.

Fixed in c039ecd, both copies, but on a different reason than the one given. The construction is a reduced relative clause with an object gap, which is grammatical in English without the pronoun, the same shape as "the file another task is editing". So the sentence is not ungrammatical.

The observation underneath it is right anyway, and it is why the fix is taken rather than declined. "One another" is a fixed reciprocal pronoun, so a reader parses those two words as a unit and only backtracks on reaching the verb. A garden path in a rule that is byte-locked across the fleet costs every reader of every copy, and the explicit "that" removes it for one word.

Recording the reason precisely because these two files are carried, so the next reviewer of a downstream copy meets the same construction elsewhere and should decline it as a grammar finding while still taking it as a readability one.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

… that blocks on what it cannot read (#609) Promotes 14 commits from `develop`. Merge with a **merge commit** (`gh pr merge --merge`), never a squash, and **without `--delete-branch`**, since this pull request's head is `develop` itself. Closes #607 through the closing keyword already carried in `530cf71`, which is why it is not repeated here. ## The prose backlog, cleared end to end `#600`, `#604`, `#605`, `#606` took the tree from **557 findings across 45 files to 0 across 0**, in four batches ordered by surface: snippets, comments, hub-only Markdown, then the carried files. Each batch measured the checker's own exemption against the live corpus *before* sweeping, and twice the measured answer was **"do not change the checker"**, which is a result of that pass rather than a skipped one. `#594` added the floor that makes those numbers trustworthy: a diff-scoped run now asserts what it actually scanned, since a check whose scan matches nothing reports zero findings and reads exactly like a pass. One finding from that work is worth carrying up: an exemption that is too **loose** produces silence rather than false positives. #519 recorded the governance files as clean; today's checker reports 38 findings against those same files as they stood at the commit that measured them. ## A review loop that fails closed `#599`, `#601`, `#602`, `#603` and `#608` are one arc on `scripts/pr_review.py`, each removing a shape in which the loop reported a clean pass over a review it had misread: - **`#599`** removed the shape a reply kept failing in, by taking the thread's *words* rather than an id, so there is no argument a hand-typed `PRRT_...` fits in. - **`#602`** made `claims` resolve what a description points at rather than what it looks like. - **`#603`** gave a disproved claim a home the next round reads. - **`#608`** reads the file-coverage line, and then generalizes: every reader keys on a structural marker, so a marker that changes spelling is a section the reader stops finding and reports as absent. The digest now vets headings, `<summary>` texts, metadata labels, coverage wordings and the reviewer login against an inventory measured from **332 review bodies**, and **blocks on anything outside it**, exit `43`, with the remedy stated as filing an issue on the hub. Whether to merge regardless is the maintainer's decision. `GOVERNANCE.md` merge gate went from four preconditions to **five** accordingly. ## Governance and tooling - **`#593`** states which checkout an agent works in and what the hub is, which is the host-wide routing the repositories that most need it cannot carry. - **`#596`** gates the pattern-detectable half of the representative-data rule, honest that no pattern closes the name-shaped case. - **`#598`** declares where a repository states what CI cannot verify. - **`#592`** regrouped `TODO.md` by what ships rather than by what it touches, so a `###` heading is one pull request. - **`#601`** ended a `gh push` argument list at a newline rather than only at `&&`, fixing a write-guard over-block. ## Verification Run on `develop` at `530cf71` immediately before opening this: `test_pr_review.py` (174), `test_prose_lint.py`, `test_repo_gate.py`, `spec/audit.py --selftest`, `gh-write-guard.py --selftest`, `spec/validate.py`, `repo_gate.py`, the prose gate in both CI invocations, markdownlint and editorconfig-checker. All clean. ## Not carried by this promotion - **#519 is complete and still open.** `TODO.md` holds its closing evidence under "Verified Complete, Awaiting Close". Closing it is the maintainer's call, so no keyword for it appears here. - **The re-vendor debt is now nine files.** `#606` queued seven, and `#608` changed `GOVERNANCE.md` "PR Review Etiquette" (`verbatim`) and `.github/copilot-instructions.md` (`intent`) on top. The `intent` half produces no hash and therefore no audit finding, which is why the Fleet Sweeps entry names those files by hand. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Copilot AI lite review requested due to automatic review settings August 6, 2026 22:59

Copilot started reviewing on behalf of ptr727 August 6, 2026 23:00 View session